package com.zenithmind.document.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.zenithmind.document.pojo.domain.DocumentAccessLog;
import com.zenithmind.document.pojo.query.DocumentAccessLogQueryDTO;
import com.zenithmind.document.pojo.vo.DocumentAccessLogVO;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 文档访问日志映射器
 * 遵循单一职责原则：专注于访问日志数据访问
 * 遵循依赖倒置原则：定义抽象的数据访问接口
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
@Mapper
public interface DocumentAccessLogMapper extends BaseMapper<DocumentAccessLog> {

    /**
     * 分页查询访问日志详情
     * 
     * @param page 分页参数
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<DocumentAccessLogVO> selectAccessLogPageWithDetails(Page<DocumentAccessLogVO> page, @Param("query") DocumentAccessLogQueryDTO queryDTO);

    /**
     * 查询文档访问日志
     * 
     * @param documentId 文档ID
     * @param limit 限制数量
     * @return 访问日志列表
     */
    List<DocumentAccessLogVO> selectDocumentAccessLogs(@Param("documentId") String documentId, @Param("limit") Integer limit);

    /**
     * 查询用户访问日志
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 访问日志列表
     */
    List<DocumentAccessLogVO> selectUserAccessLogs(@Param("userId") String userId, @Param("limit") Integer limit);

    /**
     * 查询访问统计
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 统计信息
     */
    Object selectAccessStatistics(@Param("documentId") String documentId, @Param("days") Integer days);

    /**
     * 查询热门访问文档
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return 文档列表
     */
    List<Object> selectHotAccessDocuments(@Param("days") Integer days, @Param("limit") Integer limit);

    /**
     * 查询访问趋势
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 趋势数据
     */
    List<Object> selectAccessTrend(@Param("documentId") String documentId, @Param("days") Integer days);

    /**
     * 查询用户访问行为分析
     * 
     * @param userId 用户ID
     * @param days 统计天数
     * @return 行为分析数据
     */
    Object selectUserAccessBehavior(@Param("userId") String userId, @Param("days") Integer days);

    /**
     * 查询IP访问统计
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return IP统计数据
     */
    List<Object> selectIpAccessStatistics(@Param("days") Integer days, @Param("limit") Integer limit);

    /**
     * 查询设备访问统计
     * 
     * @param days 统计天数
     * @return 设备统计数据
     */
    List<Object> selectDeviceAccessStatistics(@Param("days") Integer days);

    /**
     * 查询浏览器访问统计
     * 
     * @param days 统计天数
     * @return 浏览器统计数据
     */
    List<Object> selectBrowserAccessStatistics(@Param("days") Integer days);

    /**
     * 查询访问时间分布
     * 
     * @param days 统计天数
     * @return 时间分布数据
     */
    List<Object> selectAccessTimeDistribution(@Param("days") Integer days);

    /**
     * 检测异常访问
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param ipAddress IP地址
     * @return 是否异常
     */
    Boolean detectAbnormalAccess(@Param("documentId") String documentId, @Param("userId") String userId, @Param("ipAddress") String ipAddress);

    /**
     * 清理过期访问日志
     * 
     * @param retentionDays 保留天数
     * @return 清理数量
     */
    Integer cleanupExpiredLogs(@Param("retentionDays") Integer retentionDays);

    /**
     * 导出访问日志
     * 
     * @param queryDTO 查询条件
     * @return 导出数据
     */
    Object exportAccessLogs(@Param("query") DocumentAccessLogQueryDTO queryDTO);

    /**
     * 查询实时访问统计
     * 
     * @return 实时统计数据
     */
    Object selectRealTimeAccessStatistics();

    /**
     * 查询访问地域分布
     * 
     * @param days 统计天数
     * @return 地域分布数据
     */
    List<Object> selectAccessLocationDistribution(@Param("days") Integer days);

    /**
     * 查询访问来源统计
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return 来源统计数据
     */
    List<Object> selectAccessSourceStatistics(@Param("days") Integer days, @Param("limit") Integer limit);

    /**
     * 查询访问路径分析
     * 
     * @param userId 用户ID
     * @param days 统计天数
     * @return 路径分析数据
     */
    List<Object> selectAccessPathAnalysis(@Param("userId") String userId, @Param("days") Integer days);

    /**
     * 查询访问会话统计
     * 
     * @param days 统计天数
     * @return 会话统计数据
     */
    Object selectAccessSessionStatistics(@Param("days") Integer days);

    /**
     * 批量插入访问日志
     * 
     * @param logs 访问日志列表
     * @return 插入数量
     */
    Integer batchInsertAccessLogs(@Param("list") List<DocumentAccessLog> logs);

    /**
     * 同步访问统计
     * 
     * @return 影响行数
     */
    Integer syncAccessStatistics();

    /**
     * 查询访问频率统计
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param hours 小时数
     * @return 访问次数
     */
    Integer selectAccessFrequency(@Param("documentId") String documentId, @Param("userId") String userId, @Param("hours") Integer hours);

    /**
     * 查询用户访问偏好
     * 
     * @param userId 用户ID
     * @param days 统计天数
     * @return 偏好数据
     */
    Object selectUserAccessPreferences(@Param("userId") String userId, @Param("days") Integer days);

    /**
     * 查询文档访问峰值时间
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 峰值时间数据
     */
    List<Object> selectDocumentAccessPeakTimes(@Param("documentId") String documentId, @Param("days") Integer days);

    /**
     * 查询访问来源分析
     * 
     * @param days 统计天数
     * @return 来源分析数据
     */
    List<Object> selectAccessSourceAnalysis(@Param("days") Integer days);

    /**
     * 查询访问质量分析
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 质量分析数据
     */
    Object selectAccessQualityAnalysis(@Param("documentId") String documentId, @Param("days") Integer days);

    /**
     * 查询访问转化率
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 转化率数据
     */
    Object selectAccessConversionRate(@Param("documentId") String documentId, @Param("days") Integer days);

    /**
     * 查询访问留存率
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 留存率数据
     */
    Object selectAccessRetentionRate(@Param("documentId") String documentId, @Param("days") Integer days);

    /**
     * 查询访问跳出率
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 跳出率数据
     */
    Object selectAccessBounceRate(@Param("documentId") String documentId, @Param("days") Integer days);

    /**
     * 查询访问深度分析
     * 
     * @param userId 用户ID
     * @param days 统计天数
     * @return 深度分析数据
     */
    Object selectAccessDepthAnalysis(@Param("userId") String userId, @Param("days") Integer days);

    /**
     * 查询访问热力图数据
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 热力图数据
     */
    List<Object> selectAccessHeatmapData(@Param("documentId") String documentId, @Param("days") Integer days);
}
